package com.lipaluma.annotations.mapping;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import com.lipaluma.field.mapper.AutomaticFieldMapper;
import com.lipaluma.field.mapper.FieldMapper;
import com.lipaluma.field.mapper.single.impl.CollectionFieldMapper;

/**
 * Standard optional annotation used to describe the mapping between the field and a column of the entry file.<p>
 * 
 * To load an entry file to objects, we can map by different ways : 
 * <ul>
 * <li>by index : map the column at the position index in the entry file (This option is choosen when both are filled).</li>
 * <li>by name : map the column header found with the same name in the entry file</li>
 * <li>by field name : map the column header found with the same name of the field (both are not filled)</li>
 * </ul>
 * 
 * To write a file from objects, the user has to enter the index value. <br>
 * The name can be used to give a column header name in the entry file different of the field name
 * 
 * @author Mario
 */
@Documented
@Inherited
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface MapPath {
	/**
	 * path of the entry file
	 */
	String path() default "";

	/**
	 * the path will be present on the result marshalled even if the value is empty
	 * @return
	 */
	boolean mandatoryPresence() default false;
	
	/**
	 * optional : pattern used to format the data.
	 */
	String pattern() default "";

	/**
	 * optional : locale used to define the locale for a date or a numeric value.
	 */
	String locale() default "";

	/**
	 * optional : default value is false
	 */
	boolean required() default false;
	
	/**
	 * trim : default value is false
	 */
	boolean trim() default false;
	
	/**
	 * determine a separator on the value extracted. <br/>
	 * This attribute is used by some FieldMapper that will split the extracted value by the separator.
	 * 
	 * @see {@link CollectionFieldMapper}
	 */
	String separator() default "";
	
	/**
	 * Used with the separator. When the value extracted is splitted. By default, the empties string on result are not kept.<br/>
	 * To override this default strategy and keep all values, put this attribute at true.
	 * 
	 * @see {@link CollectionFieldMapper}
	 */
	boolean keepAll() default false;

	/**
	 * Used to map a boolean field. These strings values represents the false value
	 */
	String[] falseValues() default {};
	/**
	 * Used to map a boolean field. These strings values represents the true value
	 */
	String[] trueValues() default {};

	/**
	 * optional : define the class uses to map the field
	 * <p>
	 * by default : the mapping will be choosen automatically.
	 */
	Class<? extends FieldMapper> with() default AutomaticFieldMapper.class;

}
